DoTranslateFileProcPtr

DoTranslateFileProcPtr
Header:	TranslationExtensions.h		Carbon status:	Supported

Defines a pointer to a file translation callback function. Your file translation callback function translates a document from one format into another.

typedef ComponentResult(* DoTranslateFileProcPtr) (
    ComponentInstance self, 
    TranslationRefNum refNum, 
    const FSSpec *sourceDocument, 
    FileType srcType, 
    SInt32 srcTypeHint, 
    const FSSpec *dstDoc, 
    FileType dstType, 
    SInt32 dstTypeHint
);

You would declare your function like this if you were to name it MyDoTranslateFileCallback:

ComponentResult MyDoTranslateFileCallback (
    ComponentInstance self, 
    TranslationRefNum refNum, 
    const FSSpec *sourceDocument, 
    FileType srcType, 
    SInt32 srcTypeHint, 
    const FSSpec *dstDoc, 
    FileType dstType, 
    SInt32 dstTypeHint
);

self

A component instance that identifies the component containing your translation extension.

refNum

The translation reference number for this translation.

Macintosh Easy Open assigns this reference number to the translation. Each translation is assigned a unique number to distinguish the translation from any other translations that might occur. You need to pass this reference number to any Macintosh Easy Open functions you call from within the file translation extension; for instance, if by calling the SetTranslationAdvertisement function you display the progress dialog box, you’ll pass that reference number in the refNum parameter.

sourceDocument

A file system specification structure that specifies the document to translate.

srcType

The format of the file to be translated.

srcTypeHint

The value in the hint field of the source document’s file type specification.

dstDoc

A file system specification structure that specifies the destination document.

Your function should put the translated document into the file specified by this parameter. The data fork of the destination file already exists by the time your function is called. In addition, if the flags field in the appropriate destination file type specification in your extension’s file translation list has the taDstDocNeedsResourceFork bit set, the destination file already contains a resource fork. Your function should open the destination file and fill its data or resource fork (or both) with the appropriate translated data.

dstType

The format into which to translate the source document.

dstTypeHint

The value in the hint field of the destination document’s file type specification.

function result: If successful, your function should return noErr. Otherwise, your function should return an appropriate result code. If it cannot translate the source file, your function should return a result code different from noErr. In that case, Macintosh Easy Open will automatically delete the destination file. The Component Manager requires this function to return a value of type ComponentResult to simplify dispatching.

DISCUSSION

A file translation extension must respond to the kTranslateTranslateFile request code. You can handle this request by calling the Component Manager function CallComponentFunctionWithStorage and passing it a pointer to your file translation function.

Your file translation function can translate the source file itself or rely upon external translators.

Your translation extension should call the SetTranslationAdvertisement function to display the progress dialog box and the UpdateTranslationProgress function to update the dialog box periodically.

AVAILABILITY

Supported in Carbon.